Expose the agent provider contract for all agent types - #22

@manfred-brands Even though the code is small, this interface and it's comments describe how we want the engine to acquire and interact with agents in the future. It was previously an internal interface used only for the single type of agent we supported up to now. We think this will work for all three types: in-process, local process and remote. It's due to the remote agents, supplied by a server, that we need to make this a public external interface. Because we now use multiple agent providers we have introduced the notion that each provider has ownership of the agents it supplies and needs to take care of any cleanup when they are released.

Bottom line, this is a design review as well as a code review. Neil and I did the design, so I think your separate review is a good idea in case we missed anything.

@manfred-brands @CharliePoole, thank you. I agree with simplifying the redundant sentence and consistently using “acquired” in the parameter documentation.

By an unconfirmed acquisition outcome I meant, for example, that the remote host creates an agent but its reply is lost. GetAgent can then fail even though an agent exists on the host. The provider must determine what was created and handle its ownership and cleanup; the caller cannot assume that the failed call created nothing. I will replace “reconciling an outcome” with that concrete explanation, including equivalent wording for a failed return.

On naming, I lean toward GetAgent/ReturnAgent. GetAgent can acquire an existing or newly created agent; ReturnAgent clearly ends the caller's right to use it while leaving the provider to decide whether to reuse it or stop it. This follows the Get/Return terminology you cited without requiring every provider to implement a pool. AcquireAgent/ReturnAgent would also work if the team prefers the more explicit acquisition name.

I suggest agreeing the method names here before changing the public contract and engine call sites together. I will keep the existing signatures until that is settled.

Prepared by Neil Colvin with assistance from OpenAI Codex.

Let's go with GetAgent / ReturnAgent.

In the comment text, I'd like to retain the existing emphasis on the client not knowing whether a provider is a factory, a pool of agents or something else and not knowing what resources it manages. On the client side, we can talk about "getting," "acquiring" and "obtaining" without confusion but should use "return" consistently. We should always refer to the provider as a "provider" unless somebody can think of a word that's synonymous rather than having a more specific meaning as do "factory" and "pool." The provider "provides" agents or "returns" them. It may or may not create them, for example.

For reference purposes... we currently recognize three types of agents -- there could be more some day -- as follows...

• LocalProcess this provider is, in fact a factory for agents running on a separate local process. As in the past, agents are not reused but simply disposed upon return.
• InProcess this provider loads a single agent and will reuse it if possible.
• RemoteProcess this provider will use an interface we have yet to define to select remote servers. The servers will provide agents. There's no decision so far on reuse here.

General notes on reuse...

• Agents are tailored to specific packages, so any pool of agents would need to be indexed by key characteristics of the package. Defining "key" is the difficult part. There's an obvious tradeoff here, which depends on how costly it is to create an agent.
• An in-between option would be maintaining the process and wrapping it with a new agent. A similar examination of tradeoffs would apply.
• The immediate solution is pretty obvious... not to provide any reuse at all in the initial implementation and most likely in the initial release of 4.0.

@oznetmaster Is this enough for you to update? We'll then re-review and hopefully merge.

Although not part of this PR, the talk of naming makes me think of this question...

I removed the (unused) TestAgentService and made TestAgency the top level provider. LocalTestAgentProvider now has most of the code that was previously in TestAgency. TestAgency now does what the deleted TestAgentService used to do... coordinate individual providers. It's basically a compound provider that functions as a service.

Maybe I am hanging on to the "agency" metaphor unnecessarily. Should we rename TestAgency to TestAgentService and be done with it?

@CharliePoole @manfred-brands, yes, that is enough to update. I have prepared GetAgent/ReturnAgent with "return" used consistently. I removed the redundant acquisition sentence and the unclear outcome wording, leaving the provider's cleanup responsibility stated directly. I also removed the reuse/pool details so callers need not know how the provider manages agents or resources.

The revised API builds cleanly, its 69 existing tests pass on each runtime, and an independent provider/caller compiles against the new names on both targets. The engine follow-up will need to remove its internal duplicate and adopt ReturnAgent alongside the agreed published API package.

On the separate coordinator question, I favor TestAgentService: it describes its present role as a service composing providers. I would make that a separate engine refactor, retaining the current provider composition and launcher/registration contracts.

Prepared by Neil Colvin with assistance from OpenAI Codex.